Skip to main content

Tracking Configuration

Users can control various configuration settings of a tracker to tailor how the tracking algorithm behaves. When you create a tracker in Chariot, you provide these settings (via the SDK or API) to suit your scenario (e.g., fast-moving objects might need different parameters than slow-moving ones). The key tracker configuration options include:

  • assignment_function – Association Cost Function: This setting specifies the metric used to measure the "distance" or cost between a track prediction and a new detection for data association. Options include:

    • "intersection_over_union": Use overlap between bounding boxes as the matching criteria. High overlap means it's likely the same object. This is typical for image object tracking.
    • "euclidean": Use Euclidean distance between points; this is useful if you are tracking point coordinates in a plane or pixel coordinates of an object's center.
    • "haversine": Use Haversine distance for latitude/longitude coordinates; this is useful for tracking moving objects on the Earth’s surface given geo-coordinates.
    • "mahalanobis": Use Mahalanobis distance to account for the uncertainty in the observed positions.

    You should choose a function that fits the nature of your data (e.g., IoU for image boxes, Euclidean for arbitrary Cartesian points, Haversine for GPS data). The assignment function works in tandem with the threshold below to determine matches.

  • assignment_threshold – Association Threshold (Gating Threshold): A floating-point value that defines the cutoff for considering a detection-track pair as a valid match. The meaning of this value depends on the assignment_function:

    • For "intersection_over_union", this threshold is between 0 and 1 and represents the minimum IoU required to match a detection to a track. For example, a threshold of 0.3 means a detection must overlap at least 30% with the track's predicted box to be considered.
    • For "euclidean" or "haversine", the threshold would be a distance (in the same units as your coordinates) above which a match is not allowed. For example, if assignment_function="euclidean" for pixel coordinates, you might set assignment_threshold=50 (pixels) to ignore any detection farther than 50 pixels from the predicted track position.
    • For "mahalanobis", the threshold is a unitless squared distance value that determines whether a detection matches a track based on how far it is from the predicted state, accounting for the uncertainty (covariance) in the detection. This value is usually chosen based on the inverse chi-squared distribution, which defines a statistical confidence region. Any detection whose distance exceeds the threshold is considered too far to be a valid match.
      • In two dimensional tracking (such as point_utm or point_unitless), a threshold of 5.99 corresponds to a 95% confidence region, meaning 95% of true matches should fall within that distance. If you want to be more strict, use 4.61 for 90%; use 9.21 for 99% to be more lenient.
      • In four dimensional tracking (such as box_unitless), a threshold of 9.49 corresponds to 95% confidence. At 99% confidence, you would use 11.34.
      • Use the chi2.ppf function from scipy.stats to determine the threshold for other confidence and dimensionality values. For example, chi2.ppf(0.99, df=2) should return 9.21.

    Tuning this parameter is important: A tight threshold (small gating region) reduces false matches (tracks stealing detections from others) but risks missing true matches if objects move unpredictably or detections are noisy. A looser threshold will catch more potential matches but could allow incorrect associations.

  • kind – Tracker Data Type: This specifies the type of measurements the tracker will handle, which in turn determines state modeling internally. The object tracking service supports:

    • box_latitude_longitude: For geospatial tracking using GPS coordinates. Each detection is a bounding box. Here, each detection has (x, y, w, h) and an optional covariance (4x4) for uncertainty. Each request to update the tracker must include localization metadata such that each bounding box can be localized to a coordinate point before the tracking update step is performed.
    • box_unitless: For tracking bounding boxes in an image or plane (with coordinates in pixels or normalized units). Here, each detection has (x, y, w, h) and an optional covariance (4x4) for uncertainty.
    • point_unitless: For tracking point positions in an arbitrary 2D coordinate system, e.g., tracking a centroid or keypoint. Each detection has (x, y) coordinates. Euclidean distance is used for association in this mode.
    • point_latitude_longitude: For geospatial tracking using GPS coordinates. Each detection is a latitude/longitude pair. The tracker will expect coordinates in degrees and use Haversine distance for association.
    • point_utm: For geospatial points in the UTM (Universal Transverse Mercator) coordinate system (easting, northing, zone). This is another way to track real-world coordinates with Euclidean distance (since UTM is a projected coordinate system in meters).

    Within the system, kind influences how the track state is represented (e.g., 4D state for a box vs. 2D for a point) and how distance is calculated.

  • max_missing_updates – Track Lifetime (in missed updates): An integer specifying how many consecutive update cycles a track can miss (i.e., not be matched with any detection) before the system considers it lost. For example, if max_missing_updates = 5, a track can go unmatched for up to five updates (frames) and still be kept alive (predicting its position in the interim). On the sixth missed update, the tracker will delete that track as it's presumed gone. Setting this higher allows tracks to survive longer occlusions or temporary detector failures, but if set too high, you may end up with "ghost" tracks that hang around. Conversely, a very low value might drop legitimate tracks too quickly if your detector occasionally misses an object.

  • min_lifetime_before_active – Track Confirmation Count: An integer that sets how many updates must pass before a new track is considered "active". For example, if min_lifetime_before_active = 3, the tracker will mark a track as "new" until its lifetime has exceeded three updates. It will only be marked as "active"after three updates. This helps filter out very short-lived tracks that might be noise (e.g., a single spurious detection). The downside is that very short-lived real objects might not ever be reported if they disappear before reaching the confirmation count. You can set this to 0 to treat every new detection as an immediate track (no confirmation delay).

  • Detection Confidence Filtering – Confidence Scoring Parameters: While not a single explicit setting in the tracker creation, confidence scores from your model's detections play an important role in tracking. It's considered best practice to filter or weight detections by confidence:

    • You may choose to ignore detections below a certain confidence threshold to avoid initiating tracks on very low-confidence (likely false) detections. For instance, if your detector outputs a score from 0 to 1, you might decide that only detections with scores > 0.5 are fed into the tracker. High values should reduce false positives at the cost of possibly missing real objects. In Chariot's tracker, you would enforce this by pre-filtering inference data or by setting the detector's own threshold appropriately.